﻿#region Copyright & License
//
// Project: Quark Framework
// Project site: http://quark.codeplex.com
// See the copyright statement on the project site for more details.
//
// Licensed to the Apache Software Foundation (ASF) under one or more 
// contributor license agreements. See the NOTICE file distributed with
// this work for additional information regarding copyright ownership. 
// The ASF licenses this file to you under the Apache License, Version 2.0
// (the "License"); you may not use this file except in compliance with 
// the License. You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
#endregion

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using Quark.Framework.Exceptions;

namespace Quark.Framework
{
    /// <summary>
    /// 通用上下文接口
    /// </summary>
    public interface IQuarkContext
    {
        /// <summary>
        /// 查找并返回一个符合指定命名的对象实例，
        /// 等同于对constraints参数传入null的<see cref="IQuarkContext.Lookup{T}(string, object)"/>方法调用
        /// </summary>
        /// <typeparam name="TLookupable">被查找的类型，该类型可以是被查找对象/资源的接口、基础类型</typeparam>
        /// <param name="naming">要查找的命名</param>
        /// <returns>符合查找命名的一个对象实例</returns>
        /// <exception cref="ArgumentNullException"><paramref name="naming"/>参数为空值</exception>
        /// <exception cref="InvalidNamingException"><paramref name="naming"/>不是有效命名或命名未注册</exception>
        /// <exception cref="LookupException">查找命名实例过程发生异常，内部抛出的异常统一以<see cref="LookupException"/>作为异常封装</exception>
        /// <threadsafety/>
        TLookupable Lookup<TLookupable>(string naming) where TLookupable : class, ILookupable;

        /// <summary>
        /// 查找并返回一个符合指定命名和条件的对象实例，
        /// 可利用该方法查找一个实现<see cref="IIdentifiable"/>接口且该对象实例符合<paramref name="constraints"/>查找条件的可查找对象实例，
        /// 等同于对scope参数传入"{container}"的<see cref="IQuarkContext.Lookup{T}(string, object, string)"/>方法调用
        /// </summary>
        /// <typeparam name="TLookupable">被查找的类型，该类型可以是被查找对象/资源的接口、基础类型</typeparam>
        /// <param name="naming">要查找的命名</param>
        /// <param name="constraints">被查找对象实例所需要符合的条件，该条件应具体被查找对象的不同而可能不同。传入null表示没有任何查找条件</param>
        /// <returns>返回符合查找命名和条件的一个对象实例</returns>
        /// <exception cref="ArgumentNullException"><paramref name="naming"/>参数为空值</exception>
        /// <exception cref="InvalidNamingException"><paramref name="naming"/>不是有效命名或命名未注册</exception>
        /// <exception cref="LookupException">查找命名实例过程发生异常，内部抛出的异常统一以<see cref="LookupException"/>作为异常封装</exception>
        /// <threadsafety/>
        TLookupable Lookup<TLookupable>(string naming, object constraints) where TLookupable : class, ILookupable;

        /// <summary>
        /// 在指定的范围内查找并返回一个符合指定命名和条件的对象实例，
        /// 可利用该方法在指定的容器、系统范围内查找一个实现<see cref="IIdentifiable"/>接口且该对象实例符合<paramref name="constraints"/>查找条件的可查找对象实例
        /// </summary>
        /// <typeparam name="TLookupable">被查找的类型，该类型可以是被查找对象/资源的接口、基础类型</typeparam>
        /// <param name="naming">要查找的命名</param>
        /// <param name="constraints">被查找对象实例所需要符合的条件，该条件应具体被查找对象的不同而可能不同。传入null表示没有任何查找条件</param>
        /// <param name="scope">
        /// 查找范围的字符串格式："范围1;范围2;范围3;......"
        /// <para>
        /// 每一个范围可以是一个预定义范围，也可以是一个自定义范围，"@", "#", "{", "}"均为保留字符
        /// </para>
        /// <para>
        /// 自定义范围格式："@宿主注册名称[#应用名称[#容器名称]]"
        /// </para>
        /// <list type="bullet">
        /// <listheader>
        /// <term>预定义范围列表</term>
        /// </listheader>
        /// <item>
        /// <term>"{*}"</term>
        /// <description>无范围限制，将会向所有可以连接到的服务系统发出查询</description>
        /// </item>
        /// <item>
        /// <term>"{host}"</term>
        /// <description>在当前宿主内发出查询，包括该宿主承载的所有应用实例</description>
        /// </item>
        /// <item>
        /// <term>"{application}"</term>
        /// <description>在当前应用(应用域)范围内发出查询，包括该应用(应用域)下的所有容器实例</description>
        /// </item>
        /// <item>
        /// <term>"{container}"</term>
        /// <description>在当前容器实例内发出查询</description>
        /// </item>
        /// </list>
        /// </param>
        /// <returns>返回符合查找命名和条件的一个对象实例</returns>
        /// <exception cref="ArgumentNullException"><paramref name="naming"/>或<paramref name="scope"/>参数为空值</exception>
        /// <exception cref="InvalidNamingException"><paramref name="naming"/>不是有效命名或命名未注册</exception>
        /// <exception cref="LookupException">查找命名实例过程发生异常，内部抛出的异常统一以<see cref="LookupException"/>作为异常封装</exception>
        /// <threadsafety/>
        TLookupable Lookup<TLookupable>(string naming, object constraints, string scope) where TLookupable : class, ILookupable;
    }
}
